Nebula 1/Nebula One.iso/Internet/WWW/gform.1.1/gform.txt

Text File | 1995-10-09 | 6KB | 178 lines

gform Version 1.1d notes.    10-Oct-95 HR

Also note that docco is available in HTML as gform.html and for the
latest check http://www.swin.edu.au/csit/gform.html

1.0     gform - generic web forms handler

    The problem with forms is that they all need their own
   program or script to handle the fields in the form and perform
  some sort of action. Most often you want to collect submitted forms
  in a file or send it thru the mail to yourself or someone else
  who can colate these.

   I find that web information providers are generally not programmers
   and therefor can not easily write their own form programs.

   gform addresses the problem of application style forms.
   It enables the results of a form to be formatted and send
   to a file or via the mail. ( You could also forward mail to
   a "mail-to-print" gateway and get hardcopies ).

1.1 How it works

    In HTML you use the tag FORM to specify a form and you use
    'ACTION' to describe which scipt/program will handle the form
    data. You specfy the ACTION as 'gform'

    In the HTML tag set there is a tag for comment <!-- .. -->
    What gform does is read comments that start with <!--gform ... -->
    These special comments contain commands for gform.
    Any number of these <!--gform ..--> comments maybe used anywhere
    in the file.

    (NOTE: The old TAG format of <!gform is still supported and will
     probably work Ok, but it is not the correct syntax for
     a HTML comment. Therefor the "<!--gform" form is encouraged.)

    Gform works with various FORM specifiers such as Textarea,
    radio buttons, checkboxes, multiple choice selections.

1.2 syntax of gform commands

    There are 2 types of <!--gform ... --> commandlines.

    Firstly, variables and text strings. Variables start with
    a '$' sign followed by the variable name as specified on
    the HTML INPUT tag in the HTML form file. The varables you use
    should be those that you specified in the INPUT tags.
    If the variable doesn't match, it will look for the variable
    in the"environment" (See environement variables notes).
    If it can't find it there it will return "null".
    Beaware that "type=checkbox" returns "null" if it is
    unticked. This is a side effect of how forms are handled.

    You can also specify variables by enclosing them with
    brackets and prefixing a dollar char: '$(variable)'
         This is handy if you want text straight after the variable
    name.

    Variables maybe freely mixed with text. The following example
    will send the text string and replace the "$name" variable
    with what was given in the form submission.

    <!--gform "Form submitted by: $name"-->

    You will have to specify newlines and tabs by escaping them.
    by preceding a special char with a '\'.
        The following escaped chars are recognised:

        \n    - newline
        \t    - tab
        \f    - form feed
        \r     - return
        \$    - Escape a dollar sign
        \"    - Escape a double quote
        \\    - Escape a slash

    So using the above example with a newline appended;

    <!--gform "Form submitted by: $name\n And more text"-->

2.0     There are 2 special variables $(date) and $(time) that can be
    used to return the current date and time.

2.1    Environment variables.

    An extra bit was added (6-oct-95) that returns the values
    of CGI environment variables.

    For example;

    <!--gform "Remote host is: $(REMOTE_HOST)\n"-->

    will return the value of the remote host that submitted the
    form.

    These variables can also be seen in action with the "test-cgi"
    shell script that comes with the CGI distribution.

    The following variables exist:

    SERVER_VERSION        REDIRECT_REQUEST
    SERVER_SOFTWARE        REDIRECT_URL
    SERVER_NAME        REDIRECT_STATUS
    SERVER_PORT        GATEWAY_INTERFACE
    REMOTE_HOST        SERVER_PROTOCOL
    REMOTE_ADDR        REQUEST_METHOD
    REMOTE_USER        PATH_INFO
    REMOTE_GROUP        PATH_TRANSLATED
    REMOTE_IDENT        SCRIPT_NAME
    DOCUMENT_ROOT        QUERY_STRING
    ANNOTATION_SERVER    CONTENT_TYPE
    AUTH_TYPE        CONTENT_LENGHT
    HTTP_ACCEPT
    HTTP_USER_AGENT
    HTTP_REFERER

    (The usefullness of variables with gform is debatable.
     However, it was easy to implement. The meaning of all these
    is documented elsewhere, try http://www.yahoo.com )

2.1
    The second commandline type that is recognised are lines with
    keywords.  These control where and how the form data is handled.
        The following are recognised.

    The next line will put the results in the file "/path/of/file"

    <!--gform deliver=file "/path/of/file"-->

    The next example will email the results to "[e-mail]"

    <!--GFORM deliver=mail "[e-mail]"-->

    and optionally specify a subject

    <!--gform deliver=mail "[e-mail]" subject="form Submission"-->
    To print the results directly to a printer use,

    <!--gform deliver=print "hp"-->

    where "hp" is the name of a printer as found in your /etc/printcap

    This following example displays the HTML file 'thanks.html' after
    the form has been submitted. The pathname of "thanks.html" is
    relative to your WEB directory (Absolute pathnames can also be
    given).

    <!--gform reply="thanks.html"-->

    (commands and variables are case-insensative)

    There is a compile time option that can enable tilde ( ~ )
  character file expansion. If enabled, a "~user" in the http reference
  will expand to a users home directory and a subdirectory
  if so configured.

For example;

    ~harry/foo.html

will expand to the users home directory ( plus to whatever USERDIR is
defined to be . See INSTALL notes )

and

    <!--gform reply="/~user/html/foo.html"-->

is also expanded to a users home directory.

1.4 Complete examples.

    See the files
    sample.html
    sample2.html
    sample3.html